home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / DOpus_SDK_5.5 / docs / drag.doc < prev    next >
Text File  |  1996-09-05  |  8KB  |  254 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/Drag_Routines
  4. dopus5.library/FreeDragInfo
  5. dopus5.library/GetDragImage
  6. dopus5.library/GetDragInfo
  7. dopus5.library/GetDragMask
  8. dopus5.library/HideDragImage
  9. dopus5.library/ShowDragImage
  10. dopus5.library/StampDragImage
  11. dopus5.library/Drag_Routines                     dopus5.library/Drag_Routines
  12.  
  13.     PURPOSE
  14.  
  15.     No, this isn't a new form of software-based caberet act. The drag
  16.     routines in the dopus5.library make it easy for you to implement your
  17.     own drag and drop system.
  18.  
  19.     The DragInfo structure is the key of this system. Calling the
  20.     GetDragInfo() function will create one of these structures, and you
  21.     use it in all subsequent calls.
  22.  
  23.     The important fields of the DragInfo structure are :
  24.  
  25.         flags     You can set flags to modify the behavior of dragged images.
  26.  
  27.                   DRAGF_OPAQUE indicates that the drag image should be opaque;
  28.                   that is, colour 0 does not allow the background to show
  29.                   through.
  30.  
  31.                   DRAGF_NO_LOCK indicates that the drag routines should not
  32.                   lock the screen layers themselves.
  33.  
  34.                   DRAGF_TRANSPARENT indicates that the drag image should be
  35.                   transparent. Used in conjunction with DRAGF_OPAQUE, it
  36.                   allows you to create irregular shaped images.
  37.  
  38.         drag_rp   This is a RastPort that you can use to draw into the
  39.                   drag image.
  40.  
  41.     The other fields of the DragInfo structure can be used by you, but
  42.     normally they should be left alone.
  43.  
  44.     The usual process of dragging an image is :
  45.  
  46.         1. GetDragInfo()
  47.         2. Either render into di->drag_rp or call GetDragImage()
  48.         3. Call GetDragMask() if you rendered directly
  49.         4. If you set DRAGF_NO_LOCK, LockLayers()
  50.         5. Multiple calls to ShowDragImage() to make the image visible
  51.            and move it around (in response to mouse movements)
  52.         6. FreeDragInfo() to remove the image
  53.         7. If DRAGF_NO_LOCK was set, UnlockLayers()
  54.  
  55.     The Amiga OS has a bug which can cause a deadlock if another task attempts
  56.     to call LockLayers() while you have them locked. If you are dragging over
  57.     the entire screen rather than an individual window, you will need to take
  58.     additional steps to prevent this deadlock.
  59.  
  60.     You need to set up a timer event, roughly every half second or so (the
  61.     dopus5.library timer routines are ideal for this purpose). You also need
  62.     to have the IDCMP_INTUITICKS flag set for your window. You then must
  63.     keep a count of the number of IDCMP_INTUITICKS messages received. Every
  64.     time your periodic timer event comes around, you must examine this count
  65.     to see if it has changed. As INTUITICKS are sent roughly every 10th of
  66.     a second, one or more should have been received between each of your
  67.     timer events. If no INTUITICKS were received, it's a fair bet that
  68.     Intuition has deadlocked itself, and you should immediately call
  69.     UnlockLayers() (or HideDragImage()) to unfreeze the system.
  70.  
  71. dopus5.library/FreeDragInfo                       dopus5.library/FreeDragInfo
  72.  
  73.     NAME
  74.         FreeDragInfo - frees a DragInfo structure
  75.  
  76.     SYNOPSIS
  77.         FreeDragInfo(drag)
  78.                       A0
  79.  
  80.         void FreeDragInfo(DragInfo *);
  81.  
  82.     FUNCTION
  83.         This function removes a drag image from the display if it is still
  84.         visible, and frees the DragInfo structure.
  85.  
  86.     INPUTS
  87.         drag - structure to free
  88.  
  89.     SEE ALSO
  90.         GetDragInfo()
  91.  
  92. dopus5.library/GetDragImage                       dopus5.library/GetDragImage
  93.  
  94.     NAME
  95.         GetDragImage - pick up on-screen imagery to drag
  96.  
  97.     SYNOPSIS
  98.         GetDragImage(drag, x, y)
  99.                       A0  D0 D1
  100.  
  101.         void GetDragImage(DragInfo *, long, long);
  102.  
  103.     FUNCTION
  104.         This routine copies on-screen image data into the rastport of the
  105.         specified DragInfo structure. If the drag image is visible when this
  106.         routine is called, it is cleared before the data is copied.
  107.  
  108.     INPUTS
  109.         drag - DragInfo structure
  110.         x - x-position on screen
  111.         y - y-position on screen
  112.  
  113.     RESULT
  114.         The image data is copied from the Bitmap of the Window that was
  115.         specified when the drag image was created. This routine calls
  116.         GetDragMask() automatically.
  117.  
  118.     SEE ALSO
  119.         GetDragInfo()
  120.  
  121. dopus5.library/GetDragInfo                         dopus5.library/GetDragInfo
  122.  
  123.     NAME
  124.         GetDragInfo - create a DragInfo structure
  125.  
  126.     SYNOPSIS
  127.         GetDragInfo(window, rastport, width, height, need_gels)
  128.                       A0       A1       D0     D1       D2
  129.  
  130.         DragInfo *GetDragInfo(struct Window *, struct RastPort *,
  131.                               long, long, long);
  132.  
  133.     FUNCTION
  134.         Creates a DragInfo structure that is used to implement drag and drop.
  135.         Drags are inherently attached to a particular RastPort (usually either
  136.         a screen's or a window's). The drag system is implemented using BOBs,
  137.         which require a GelsInfo structure to be attached to the destination
  138.         RastPort. This routine can do this for you if you desire.
  139.  
  140.     INPUTS
  141.         window - Window to attach BOB to (or NULL if rastport is supplied)
  142.         rastport - RastPort to attach BOB to (if not a window)
  143.         width - width of drag image
  144.         height - height of drag image
  145.         need_gels - set to TRUE if you would like this routine to allocate
  146.                     and initialise a GelsInfo automatically
  147.  
  148.     RESULT
  149.         If successful, a DragInfo structure is returned. Nothing is displayed
  150.         on-screen; you must create the image and display it using the other
  151.         library calls. Once you have the DragInfo structure, you can
  152.         initialise the 'flags' field as described in the introduction.
  153.  
  154.     SEE ALSO
  155.         FreeDragInfo()
  156.  
  157. dopus5.library/GetDragMask                         dopus5.library/GetDragMask
  158.  
  159.     NAME
  160.         GetDragMask - build mask for drag image
  161.  
  162.     SYNOPSIS
  163.         GetDragMask(drag)
  164.                      A0
  165.  
  166.         void GetDragMask(DragInfo *);
  167.  
  168.     FUNCTION
  169.         Once you have created the image you want to drag, you must call
  170.         this function. This builds the shadow mask used to drag the image,
  171.         and is necessary for the image to be displayed correctly.
  172.  
  173.     INPUTS
  174.         drag - DragInfo structure to build mask for
  175.  
  176.     SEE ALSO
  177.         GetDragInfo()
  178.  
  179. dopus5.library/HideDragImage                     dopus5.library/HideDragImage
  180.  
  181.     NAME
  182.         HideDragImage - remove a drag image from the display
  183.  
  184.     SYNOPSIS
  185.         HideDragImage(drag)
  186.                        A0
  187.  
  188.         void HideDragImage(DragInfo *);
  189.  
  190.     FUNCTION
  191.         This routine removes a visible drag image from the display.
  192.  
  193.     INPUTS
  194.         drag - DragInfo structure
  195.  
  196.     SEE ALSO
  197.         ShowDragImage()
  198.  
  199. dopus5.library/ShowDragImage                     dopus5.library/ShowDragImage
  200.  
  201.     NAME
  202.         ShowDragImage - display a drag image
  203.  
  204.     SYNOPSIS
  205.         ShowDragImage(drag, x, y)
  206.                        A0  D0 D1
  207.  
  208.         void ShowDragImage(DragInfo *, long, long);
  209.  
  210.     FUNCTION
  211.         This routine displays a drag image at a given location. The image is
  212.         displayed in the RastPort that was supplied to the GetDragInfo() call.
  213.         If the image was not already displayed, it is added to the display.
  214.         If it was, it is removed from its current position and redisplayed in
  215.         the new location. This is the main call used to move an image around
  216.         the screen.
  217.  
  218.     INPUTS
  219.         drag - DragInfo structure to display
  220.         x - x position in rastport
  221.         y - y position in rastport
  222.  
  223.     SEE ALSO
  224.         GetDragInfo(), HideDragImage()
  225.  
  226. dopus5.library/StampDragImage                   dopus5.library/StampDragImage
  227.  
  228.     NAME
  229.         StampDragImage - stamp drag image onto the screen
  230.  
  231.     SYNOPSIS
  232.         StampDragImage(drag, x, y)
  233.                         A0  D0 D1
  234.  
  235.         void StampDragImage(DragInfo *, long, long);
  236.  
  237.     FUNCTION
  238.         This routine stamps the drag image onto the bitmap at the given
  239.         location. Using this function would allow you to "paint" with the
  240.         drag image.
  241.  
  242.     INPUTS
  243.         drag - DragInfo structure
  244.         x - x position to stamp image at
  245.         y - y position to stamp image at
  246.  
  247.     RESULT
  248.         The image is drawn into the RastPort that was supplied in the
  249.         GetDragInfo() call.
  250.  
  251.     SEE ALSO
  252.         GetDragInfo(), ShowDragImage()
  253.  
  254.